/*
 * MIT License
 * 
 * Copyright (c) 2017 wen.gu <454727014@qq.com>
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/***************************************************************************
 * Name: vos_mem.h
 *
 * Purpose: virtual os layer about memory operation interface
 *
 * Developer:
 *   wen.gu , 2015-10-12
 *
 * TODO: 
 *
 ***************************************************************************/

#ifndef __VOS_MEM_H__
#define __VOS_MEM_H__

#include "general_type.h"

#ifdef __cplusplus
extern "C"{
#endif

/***************************************************************************
 *
 * macro define
 *
 ***************************************************************************/
/** open this when need debug memory(eg. leak, overflow ) */
//#define MEM_DEBUG
/***************************************************************************
 *
 * virtual memory API declaration
 *
 ***************************************************************************/
/**
*@brief  allocate a memory
*
*@param  size [in] allocate memory size
*
*@return if success return memory porinter, else return 'NULL'.
*@see 
*/
G_API void *memAlloc(GU32 size);

/**
*@brief  reallocate a memory
*
*note    if you want not lost data,the new
*        size must bigger than old memory size
*
*@param  oldMem  [in] old memory addr
*@param  newSize [in] new memory size
*
*@return if success return new memory porinter, else return 'NULL'.
*@see 
*/
G_API void *memRealloc(void* oldMem, GU32 newSize);

/**
*@brief  free a memory
*
*@param  mem [in] memory addr
*
*@return None.
*@see 
*/
G_API void memFree(void* mem);



#if defined(MEM_DEBUG)
#define memAlloc(size) memAllocDebug(size, __FUNCTION__, __LINE__)
#define memRealloc(oldMem, newSize) memReallocDebug(oldMem, newSize, __FUNCTION__, __LINE__)
#define memFree(mem) memFreeDebug(mem, __FUNCTION__, __LINE__)

/***************************************************************************
 *
 * virtual memory API for debug(needn't portable implement)
 *
 ***************************************************************************/

/**
 *@brief  allocate a memory
 *
 *@param  size [in] allocate memory size
 *@param  func_name [in] which function called 'memAllocDebug'.
 *@param  line_num  [in] the line number of function called.
 *
 *@return success: memory porinter, fail: 'NULL'.
 *@see
 *@note   user needn't direact call this function,it will be called
 *        in debug mode by macro define.
 */
G_API void *memAllocDebug(GU32 size, const char* func_name, GS32 line_num);

/**
 *@brief  reallocate a memory
 *
 *note    if you want not lost data,the new
 *        size must bigger than old memory size
 *
 *@param  oldMem  [in] old memory addr
 *@param  newSize [in] new memory size
 *@param  func_name [in] which function called 'memReallocDebug'.
 *@param  line_num  [in] the line number of function called.
 *
 *@return success: new memory porinter, fail: 'NULL'.
 *@see 
 *@note   user needn't direact call this function,it will be called
 *        in debug mode by macro define.
 */
G_API void *memReallocDebug(void* oldMem, GU32 newSize, 
                              const char* func_name, GS32 line_num);

/**
 *@brief  free a memory
 *
 *@param  mem [in] memory addr
 *@param  func_name [in] which function called 'memFreeDebug'.
 *@param  line_num  [in] the line number of function called.
 *
 *@return None.
 *@see 
 *@note   user needn't direact call this function,it will be called
 *        in debug mode by macro define.
 */
G_API void memFreeDebug(void* mem, const char* func_name, GS32 line_num);

/**
 *@brief  initialize memory debug env.
 *
 *@param  None
 *
 *@return success: G_OK, fail: error code.
 *@see 
 *@note  1. this API called at start of the program,
 *       2. only can call once.
 */
G_API GS32 memDebugInit();

/**
 *@brief  uninitialize memory debug env.
 *
 *@param  None
 *
 *@return success: G_OK, fail: error code.
 *@see 
 *@note  1. this API called at end of the program, 
 *       2. this API will log out information of memory leak/overflow, if have
 *       3. this API will release the resource of memory debug env,
 *       4. only can call once.
 *       
 */
G_API void memDebugUninit();

#endif

#ifdef __cplusplus
}
#endif

#endif //end of __VOS_MEM_H__
